home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 1 / Gold Medal Software Volume 1 (Gold Medal) (1994).iso / prog / cextract.arj / CEXTRACT.TAR / cextract / cextract.doc < prev    next >
Encoding:
Text File  |  1993-08-08  |  13.2 KB  |  397 lines
  1.  
  2.  
  3.  
  4. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      cextract, cextdoc - C prototype/documentation extractor
  10.  
  11. SYNOPSIS
  12.      cextract [ -Q# ] [ +AaPpNnxZ ] [ -o ofile ] [  -Hstr  -Yprog
  13.      -B -b -V -v ] [[ -options ] filename... ]
  14.  
  15.      cextdoc [ -Q# ] [ +AaNnx ] [ -o outfile ] [ -Yprogram -B  -b
  16.      -V -v ] [[ -options ] filename... ]
  17.  
  18. DESCRIPTION
  19.      The  cextract  program  is  used  to  extract  the  function
  20.      descriptions  (aka prototypes) from a list of C source files
  21.      and send them out to the  standard  output  or  a  specified
  22.      file.   It  may also be used to generate basic documentation
  23.      for a list of C source files.
  24.  
  25.      The specific reason this program was written was to  provide
  26.      a  method of automatically generating header files, contain-
  27.      ing prototypes, for all of the functions used  throughout  a
  28.      multi-file project.
  29.  
  30.      Along with the standard C preprocessing options, -D, -I, and
  31.      -U,  there are options which allow more control of what form
  32.      the output will take.
  33.  
  34.      To allow for conditional processing, cextract  automatically
  35.      predefines  the  __CEXTRACT__ identifier.  Preprocessor com-
  36.      mands, such as "#if", "#ifdef" and  "#ifndef"  may  then  be
  37.      used  to  control  what  code is parsed by cextract.  If the
  38.      cextdoc command  is  used,  the  program  will  also  define
  39.      __CEXTDOC__.
  40.  
  41.      The cextract program also supports the use of  customization
  42.      files.   A  system configuration file will be read, and then
  43.      any ".cextrc" file in the user's home directory, and finally
  44.      any ".cextrc" file in the current directory.  For a descrip-
  45.      tion of the  format  of  the  customization  file,  see  the
  46.      cextrc(5) manual page.
  47.  
  48. COMMAND LINE OPTIONS
  49.      The cextract and cextdoc  programs  support  both  long  and
  50.      short  command  line  options.   Also,  a `+' sign before an
  51.      option description means that it can be either  on  or  off,
  52.      with a `+' prefix enabling that option or a `-' prefix disa-
  53.      bling it.  The prefix of "no-" (or "no") is  also  supported
  54.      for disabling an option.
  55.  
  56.      Most command line arguments may be used anywhere on the com-
  57.      mand  line,  but  a few must be used before any file parsing
  58.      begins [such as the -N, +Z and -x options], and one can only
  59.      be the first argument on the command line [the -Q flag].
  60.  
  61.  
  62.  
  63. Sun Release 4.1   Last change: 30 October 1992                  1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  71.  
  72.  
  73.  
  74.      +A, +sort-all
  75.           Sort the output, listing all functions in  alphabetical
  76.           order.  This option is not compatible with the +C flag,
  77.           since functions are sorted over  the  entire  spectrum,
  78.           not just for each file.
  79.  
  80.      +a, +sort-by-files
  81.           Sort the output, listing functions  alphabetically  for
  82.           each   file.    Since   this  option  sorts  each  file
  83.           separately, it is compatible with the +C  flag,  unlike
  84.           the  +A option.  For cextract, the default is to not do
  85.           any sorting, while the cextdoc default is  to  sort  by
  86.           files.
  87.  
  88.      -b, -build-config
  89.           Automatically build a configuration file in the current
  90.           directory based on the current program settings.
  91.  
  92.      -B, -system-build
  93.           Generate a system wide configuration file based on  the
  94.           current program settings.
  95.  
  96.      +C, +first-comments
  97.           Capture the first comment encountered in each file  and
  98.           include it in the generated output. [default off]
  99.  
  100.      +c, +comments, +yank-comments
  101.           Take the comment  immediately  preceding  the  function
  102.           declaration  and send it as output along with the func-
  103.           tion prototype. [default on]
  104.  
  105.      -Dexpression, -define=expression
  106.           Define a macro, as per  the  C  "#define"  preprocessor
  107.           statement.
  108.  
  109.      +E, +externs
  110.           Place the string 'extern' before each  function  proto-
  111.           type. [default on]
  112.  
  113.      +F, +filename
  114.           Prepend the name of the file  to  the  initial  comment
  115.           when  it  is  processed.   This  flag  requires  the +C
  116.           option. [default off]
  117.  
  118.      -f%##, -font-%-##
  119.           Specify what fonts are to be used when generating troff
  120.           documentation  output.   The  font name is a one or two
  121.           character troff name which will be interpreted later by
  122.           the  troff  processor.  Four fonts are used: `1' or `t'
  123.           which is used only for the title words "Function:"  and
  124.           "File:"  [default  value  of  "C", Courier]; `2' or `c'
  125.           which is used for  comments  [default  value  of  "CO",
  126.  
  127.  
  128.  
  129. Sun Release 4.1   Last change: 30 October 1992                  2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  137.  
  138.  
  139.  
  140.           Courier  Oblique];  `3'  or  `n'  which is used for the
  141.           function name [default value of "B", Times  Bold];  and
  142.           `4'  or  `p'  for  the parameter list [default value of
  143.           "R", Times Roman].  Note that the `%'  character  indi-
  144.           cates  the  type being adjusted, and "##" indicates the
  145.           one or two character font name.
  146.  
  147.      -Hstring, -header-string=string
  148.           During the normal extraction mode, enclose  the  output
  149.           within the sequence "#ifndef string", "#define string",
  150.           ..., "#endif /* string */".  This method is  used  with
  151.           many  system  header files and prevents the header file
  152.           from being parsed more than once.  If  this  option  is
  153.           not used, the output will be enclosed within a "#ifndef
  154.           __CEXTRACT__", "#endif  /*  __CEXTRACT__  */"  sequence
  155.           instead.
  156.  
  157.      -Idirectory, -include=directory
  158.           Add the indicated directory  to  the  search  path  for
  159.           include  files accessed via the "#include" preprocessor
  160.           statement.  This flag is passed on to the C  preproces-
  161.           sor.
  162.  
  163.      +m, +multi-comments, +multiple-comments
  164.           If the -c flag is set, look for a "block"  of  multiple
  165.           comments,  instead  of a single comment.  Comments with
  166.           more  than  one  newline  in  between  are   considered
  167.           separate. [default off]
  168.  
  169.      -N, -roff-mode, -troff-mode
  170.           Enable documentation mode, sending output as -ms  troff
  171.           format.
  172.  
  173.      -n, -doc-mode
  174.           Enable documentation mode,  sending  output  as  normal
  175.           text.  This is the default mode of the cextdoc program.
  176.  
  177.      -o outfile, -output-file outfile, -output-file=outfile
  178.           Send output to the specified file instead of the  stan-
  179.           dard output.  The file name need not immediately follow
  180.           the `-o' flag, but it  must  be  the  first  non-option
  181.           argument.  Warning:  This  will  overwrite any existing
  182.           file of the same name.
  183.  
  184.      +P, +dual-output
  185.           In extraction mode, generate both styles  of  C  proto-
  186.           types,  separated  by using "#ifdef" and "#else" state-
  187.           ments to test for __STDC__.  This option  must  precede
  188.           any file arguments. [default on]
  189.  
  190.      +p, +ansi-code
  191.           Produce output in ANSI C prototype  format;  otherwise,
  192.  
  193.  
  194.  
  195. Sun Release 4.1   Last change: 30 October 1992                  3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  203.  
  204.  
  205.  
  206.           produce  old-style declarations.  This option must pre-
  207.           cede any file arguments.  [default off]
  208.  
  209.      -qfile, -config-file=file
  210.           Read in the specified file and parse it for  customiza-
  211.           tion commands.
  212.  
  213.      -Q#, -read-config=#
  214.           An octal  digit  specifies  which  configuration  files
  215.           should  be read; 1 for the system configuration file, 2
  216.           for the $HOME/.cextrc file and 4 for the ".cextrc" file
  217.           in  the current directory.  Add values to read multiple
  218.           files.  If no number is  specified,  a  0  is  assumed.
  219.           This option must be the very first argument on the com-
  220.           mand line.  [default value of 7 reads all three files]
  221.  
  222.      +r, +remove-names, +discard-names
  223.           Strip out the variable names when sending out the  pro-
  224.           totype lists.
  225.  
  226.      +S, +show-all, +show-anyway
  227.           If the -p flag is off, output the prototype  list  any-
  228.           way,  but  enclosed  within comments. If the -P flag is
  229.           set, comments and commented prototypes should  also  be
  230.           duplicated  within  the non-ANSI portion of the output.
  231.           [default on]
  232.  
  233.      +s, +s:none|all|only, +statics, +statics: none|all|only
  234.           Indicate how static functions are to  be  treated.   If
  235.           "none"  is chosen, static functions will be ignored, if
  236.           "only" then any non-static functions will  be  ignored,
  237.           and   "any"   indicates  that  all  functions  will  be
  238.           included.  If no selection is given, either "any"  (`+'
  239.           flag),  or "none" (`-' flag) will be used.
  240.  
  241.      -T#, -tab-width=#
  242.           Specify the tab width used during documentation output.
  243.           If no value is given, or a value of zero is given, tabs
  244.           are passed though unformatted.
  245.  
  246.      -Uname, -undefine=name
  247.           Undefine a macro.  If "-Dname" was specified in a  pre-
  248.           vious  argument,  it is removed from the argument list;
  249.           otherwise, this option is passed on to the C preproces-
  250.           sor.
  251.  
  252.      -V, -settings
  253.           Show  the  current  settings  of  the  various  program
  254.           options.
  255.  
  256.      -v, -version-info
  257.           Display the version number of the program.
  258.  
  259.  
  260.  
  261. Sun Release 4.1   Last change: 30 October 1992                  4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  269.  
  270.  
  271.  
  272.      +W, +break-after-types, +break-types
  273.           When enabled, a newline will be  inserted  between  the
  274.           function  type  and  the  function name in the function
  275.           declarations.
  276.  
  277.      +w#, +wrap-parameters=#
  278.           If the length of the  parameter  list  for  a  function
  279.           would  cause it to exceed a given number of columns [72
  280.           by default], a newline will be inserted in place  of  a
  281.           space  character,  so that the function will not exceed
  282.           that given length.  The optional number after the  com-
  283.           mand will override a negation prefix if encountered.
  284.  
  285.      -x, -extract-mode
  286.           Run cextract or cextdoc as a prototype extractor.  This
  287.           is the default mode for cextract.
  288.  
  289.      -Yprogram -cpp-program=program
  290.           Specify which program to use  as  the  C  preprocessor.
  291.           This  program  should  resolve all of the C defines and
  292.           preprocessor statements while, hopefully, leaving  com-
  293.           ments intact.
  294.  
  295.      +Z, -merge-output
  296.           Combine the ANSI and K&R C output of  the  cextract  on
  297.           one line, to create a much more compact header file.
  298.  
  299. VMS
  300.      Configuration files  are  also  supported  under  VMS.   The
  301.      default    configuration   files   for   VMS   systems   are
  302.      sys$library:cext.cnf, sys$login:cext.cnf, and cext.cnf.
  303.  
  304.      Since the VMS C compiler strips out comments, the documenta-
  305.      tion  mode  and  comment options are not very useful.  Using
  306.      the GNU C preprocessor instead might be a possible solution.
  307.  
  308. COPYRIGHT
  309.      The code is freely distributable and there are  no  restric-
  310.      tions  other  than the fact that it not be used for monetary
  311.      gain and that copyright notices must be kept intact.
  312.  
  313.      Both  cextract  and  cextdoc  may  be   used   to   generate
  314.      proprietary source code or documentation, but its own source
  315.      code may not be used as a part of any proprietary programs.
  316.  
  317.      The header files and documentation generated by cextract and
  318.      cextdoc  are  not  subject  to this COPYRIGHT notice because
  319.      they are derived from the source code which was read  in  by
  320.      the program to create the output.
  321.  
  322. FILES
  323.      /usr/local/lib/cext.config, $HOME/.cextrc, .cextrc
  324.  
  325.  
  326.  
  327. Sun Release 4.1   Last change: 30 October 1992                  5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  335.  
  336.  
  337.  
  338.           The list of configuration files, and the order in which
  339.           they are read in.
  340.  
  341. SEE ALSO
  342.      cc(1), cextrc(5)
  343.  
  344. AUTHORS
  345.      Adam Bryant
  346.      adb@cs.bu.edu
  347.  
  348.      initial VMS port by John Carr
  349.      jrcarr@iup.bitnet
  350.  
  351.      special thanks to comp.sources.reviewed reviewers, without whom this
  352.      program would be much less useful.
  353.  
  354. VMS
  355.      On VMS systems, only the longer  command  line  options  are
  356.      available,  and the '/' character is used to specify command
  357.      line options.
  358.  
  359. BUGS
  360.      1) As far as I know, there is no way to tell the normal  VMS
  361.      C compiler not to strip out comments.  This renders the com-
  362.      ment extraction and documentation mode portions rather  use-
  363.      less  to VMS sites.  Getting the GNU C preprocessor for such
  364.      sites is recommended.
  365.  
  366.      2) Cextract has problems with function pointers  and  struc-
  367.      ture  definitions  within the parameter list, using typedefs
  368.      for such declarations is recommended.
  369.  
  370.      3) Does not yet fully support C++ code.
  371.  
  372.      4) It is dependent on the given C preprocessor, so will have
  373.      any  limitations  (such  as  maximum  #defines)  which the C
  374.      preprocessor has.
  375.  
  376.      If any other bugs are detected, please notify the author.
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Sun Release 4.1   Last change: 30 October 1992                  6
  394.  
  395.  
  396.  
  397.